## 10.4. Configuring XFree86

Setting up XFree86 is not difficult in most cases. However, if you happen to be using hardware for which drivers are under development, or wish to obtain the best performance or resolution from an accelerated graphics card, configuring XFree86 can be somewhat time-consuming.

In this section, we describe how to create and edit the XF86Config file, which configures the XFree86 server. In many cases, it is best to start out with a "basic" XFree86 configuration--one that uses a low resolution. A good choice is 640x480, which should be supported on all video cards and monitor types. Once you have XFree86 working at a lower, standard resolution, you can tweak the configuration to exploit the capabilities of your video hardware. The idea is that you want to make sure XFree86 works at least minimally on your system and that something isn't wrong with your installation before attempting the sometimes difficult task of setting up XFree86 for real use. With current hardware, you should easily be able to get up to 1024x768 pixels.

But before you start to write a XF86Config file yourself, try one of the configuration programs that are available. In many cases, you can avoid going through the hassle that will be described on the next pages. Some programs that may help you are:

`XF86Setup`

  This graphical configuration program is provided by the XFree86 team themselves. It starts up a VGA X server with 16 colors (which is quite sure to run on just about any display hardware) and then lets you select your graphics board, your monitor type, your mouse type, and other options. At the end, it tries to start up a server as configured, and if you are satisfied, it offers to write the configuration file for you. We have found this program to be very useful and reliable in many cases.

`ConfigXF86`

  This is a text-based program that asks you a number of questions and then generates a configuration file from your answers. It is by no means as comfortable to use as `XF86Setup` (and is slightly outdated), but it has been reported to work in cases where `XF86Setup` has failed.

Distribution-specific configuration tools

  Some distributions also have their own configuration tools. For example, SuSE has `SaX` and Red Hat has `Xconfigurator`. Caldera OpenLinux now even configures the mouse and the video board automatically during installation.

If one of these tools is able to configure your X server for you, you should use it and save yourself a lot of trouble. However, if all of the tools fail or if you really want to fine-tune your X server, you will have to know how to edit the XF86Config file yourself.

In addition to the information here, you should read the following documentation:

- The XFree86 documentation in /usr/X11R6/lib/X11/doc (contained within the Xdoc package). You should especially see the file README.Config, which is an XFree86 configuration tutorial.

- The README file for your video chipset, if one exists, in the directory /usr/X11R6/lib/X11/doc. These README files have names such as README.Cirrus and README.S3.

- The manual page for XFree86.

- The manual page for XF86Config.

- The manual page for the particular server that you are using (such as XF86_SVGA or XF86_S3).

The main configuration file you need to create is /usr/X11R6/lib/X11/XF86Config (some distributions put this in /etc/XF86Config or /etc/X11 instead). This file contains information on your mouse, video card parameters, and so on. The file XF86Config.eg is provided with the XFree86 distribution as an example. Copy this file to XF86Config and edit it as a starting point.

The XF86Config manual page explains the format of this file in detail. Read this manual page now if you have not done so already.

We are going to present a sample XF86Config file, piece by piece. This file may not look exactly like the sample file included in the XFree86 distribution, but the structure is the same.

The XF86Config file format may change with each version of XFree86; this information is only valid for XFree86 Version 3.3.3.1.

Also, you should not simply copy the configuration file listed here to your own system and attempt to use it. Attempting to use a configuration file that doesn't correspond to your hardware could drive the monitor at a frequency that is too high for it; there have been reports of monitors (especially fixed-frequency monitors) being damaged or destroyed by using an incorrectly configured XF86Config file. The bottom line is this: make absolutely sure your XF86Config file corresponds to your hardware before you attempt to use it.

Each section of the XF86Config file is surrounded by the pair of lines `Section "`section-name`"`…`EndSection`. The first part of the XF86Config file is `Files`, which looks like this:

>     Section "Files"
>         RgbPath     "/usr/X11R6/lib/X11/rgb"
>         FontPath    "/usr/X11R6/lib/X11/fonts/misc/"
>         FontPath    "/usr/X11R6/lib/X11/fonts/75dpi/"
>     EndSection

The `RgbPath` line sets the path to the X11R6 RGB color database, and each `FontPath` line sets the path to a directory containing X11 fonts. In general, you shouldn't have to modify these lines; just be sure there is a `FontPath` entry for each font type you have installed (i.e., for each directory in /usr/X11R6/lib/X11/fonts). If you add the string `:unscaled` to a `FontPath`, the fonts from this directory will not be scaled. This is often an improvement because fonts that are vastly scaled look ugly. In addition to `FontPath` and `RgbPath`, you can also add a `ModulePath` to this section, to point to a directory with dynamically loaded modules. Those modules are currently used for some special input devices, as well as the PEX and XIE extensions.

The next section is `ServerFlags`, which specifies several global flags for the server. In general this section is empty:

>     Section "ServerFlags"
>     # Uncomment this to cause a core dump at the spot where a signal is
>     # received.  This may leave the console in an unusable state, but may
>     # provide a better stack trace in the core dump to aid in debugging
>     #    NoTrapSignals
>     # Uncomment this to disable the <Crtl><Alt><BS> server abort sequence
>     #    DontZap
>     EndSection

Here, we have all lines within the section commented out.

The next section is `Keyboard`:

>     Section "Keyboard"
>         Protocol    "Standard"
>         AutoRepeat  500 5
>         ServerNumLock
>     EndSection

Other options are available as well: see the XF86Config file if you wish to modify the keyboard configuration. The previous example should work for most systems with U.S. keyboards. If you have another keyboard, you will have to add additional lines. For example, the following works for a standard German keyboard:

>     XkbRules	"xfree86"
>     XkbModel	"pc102"
>     XkbLayout	"de"
>     XkbVariants	""
>     XkbOptions	""

The next section is `Pointer`, which specifies parameters for the mouse device:

>     Section "Pointer"

>         Protocol    "MouseSystems"
>         Device      "/dev/mouse"

>     # Baudrate and SampleRate are only for some Logitech mice
>     #    BaudRate   9600
>     #    SampleRate 150

>     # Emulate3Buttons is an option for 2-button Microsoft mice
>     #    Emulate3Buttons

>     # ChordMiddle is an option for some 3-button Logitech mice
>     #    ChordMiddle

>     EndSection

The only options you should concern yourself with now are `Protocol` and `Device`. `Protocol` specifies the mouse protocol your mouse uses (not the make or brand of mouse). Valid types for `Protocol` (under Linux--there are other options available for other operating systems) are:

- `BusMouse`

- `Logitech`

- `Microsoft`

- `MMSeries`

- `Mouseman`

- `MouseManPlusPS/2`

- `MouseSystems`

- `PS/2`

- `MMHitTab`

- `GlidePoint`

- `GlidePointPS/2`

- `IntelliMouse`

- `IMPS/2`

- `NetMousePS/2`

- `NetScrollPS/2`

- `SysMouse`

- `ThinkingMouse`

- `ThinkingMousePS/2`

- `Xqueue`

`BusMouse` should be used for the Logitech busmouse. Note that older Logitech mice that are not bus mice should use `Logitech`, but newer Logitech mice that are not bus mice use either the `Microsoft` or the `Mouseman` protocol. This is a case where the protocol doesn't necessarily have anything to do with the make of the mouse.

If you have a modern serial mouse, you could also try to specify `Auto`, which will try to autoselect a mouse driver.

It is easy to check whether you have selected the correct mouse driver once you have started up X; when you move your mouse, the mouse pointer on the screen should follow this movement. If it does this, your setup is very likely to be correct. If it doesn't, try another driver, and also check whether the device you specified is correct.

`Device` specifies the device file where the mouse can be accessed. On most Linux systems, this is /dev/mouse. /dev/mouse is usually a link to the appropriate serial port (such as /dev/ttyS0) for serial mice or to the appropriate busmouse device for busmice. At any rate, be sure that the device file listed in `Device` exists.

The next section is `Monitor`, which specifies the characteristics of your monitor. As with other sections in the XF86Config file, there may be more than one `Monitor` section. This is useful if you have multiple monitors connected to a system, or use the same XF86Config file under multiple hardware configurations. In general though, you will need only a single `Monitor` section:

>     Section "Monitor"

>         Identifier  "CTX 5468 NI"

>         # These values are for a CTX 5468NI only! Don't attempt to use
>         # them with your monitor (unless you have this model)

>         HorizSync    30-38,47-50
>         VertRefresh  50-90

>         # Modes: Name      dotclock  horiz                vert

>         ModeLine "640x480"  25       640 664 760 800      480 491 493 525
>         ModeLine "800x600"  36       800 824 896 1024     600 601 603 625
>         ModeLine "1024x768" 65       1024 1088 1200 1328  768 783 789 818

>     EndSection

The `Identifier` line is used to give an arbitrary name to the `Monitor` entry. This can be any string; you will use it to refer to the `Monitor` entry later in the XF86Config file.

`HorizSync` specifies the valid horizontal sync frequencies for your monitor in kHz. If you have a multisync monitor, this can be a range of values (or several comma-separated ranges), as seen in the `Monitor` section. If you have a fixed-frequency monitor, this will be a list of discrete values, such as:

>         HorizSync    31.5, 35.2, 37.9, 35.5, 48.95

Your monitor manual should list these values in the technical specifications section. If you do not have this information, you should contact either the manufacturer or the vendor of your monitor to obtain it. There are other sources of information, as well; they are listed later.

You should be careful with those settings. While the settings `VertRefresh` and `HorizSync` (described next) help to make sure that your monitor will not be destroyed by wrong settings, you won't be very happy with your X setup if you get these values wrong. Unsteady pictures, flickering, or just plain snow can result.

`VertRefresh` specifies the valid vertical refresh rates (or vertical synchronization frequencies) for your monitor in Hz. Like `HorizSync`, this can be a range or a list of discrete values; your monitor manual should list them.

`HorizSync` and `VertRefresh` are used only to double-check that the monitor resolutions you specify are in valid ranges. This reduces the chance that you will damage your monitor by attempting to drive it at a frequency for which it wasn't designed.

The `ModeLine` directive is used to specify a single resolution mode for your monitor. The format of `ModeLine` is:

>     ModeLine name dot-clock horiz-values vert-values

name is an arbitrary string, which you will use to refer to the resolution mode later in the file. dot-clock is the driving clock frequency or dot clock associated with the resolution mode. A dot clock is usually specified in MHz and is the rate at which the video card must send pixels to the monitor at this resolution. horiz-values and vert-values are four numbers each; they specify when the electron gun of the monitor should fire and when the horizontal and vertical sync pulses fire during a sweep across the screen.

How can you determine the `ModeLine` values for your monitor? The file VideoModes.doc, included with the XFree86 distribution, describes in detail how to determine these values for each resolution mode your monitor supports. First of all, clock must correspond to one of the dot-clock values that your video card can produce. Later in the XF86Config file, you will specify these clocks; you can use only video modes that have a clock value supported by your video card.

Two files included in the XFree86 distribution may include `ModeLine` data for your monitor. These files are modeDB.txt and Monitors, both of which are found in /usr/X11R6/lib/X11/doc.

You should start with `ModeLine` values for the VESA standard monitor timings, which most monitors support. modeDB.txt includes timing values for VESA standard resolutions. In that file, you will see entries such as:

>     # 640x480@60Hz Non-Interlaced mode
>     # Horizontal Sync = 31.5kHz
>     # Timing: H=(0.95us, 3.81us, 1.59us), V=(0.35ms, 0.064ms, 1.02ms)
>     #
>     # name        clock   horizontal timing     vertical timing      flags
>      "640x480"     25.175  640  664  760  800    480  491  493  525

This is a VESA standard timing for a 640x480 video mode. It uses a dot clock of 25.175, which your video card must support to use this mode (more on this later).

To include this entry in the XF86Config file, you'd use the line:

>     ModeLine "640x480" 25.175  640 664 760 800  480 491 493 525

Note that the name argument to `ModeLine` (in this case `"640x480"`) is an arbitrary string; the convention is to name the mode after the resolution, but name can technically be anything descriptive that describes the mode to you.

For each `ModeLine` used, the server checks that the specifications for the mode fall within the range of values specified with `HorizSync` and `VertRefresh`. If they do not, the server will complain when you attempt to start up X (more on this later).

If the VESA standard timings do not work for you (you'll know after trying to use them later when the screen is unsteady, flickers, or shows snow), the files modeDB.txt and Monitors include specific mode values for many monitor types. You can create `ModeLine` entries from the values found in those two files as well. Be sure to use values only for your specific model. Note that many 14- and 15-inch monitors cannot support higher-resolution modes and often can support resolutions of 1024x768 at low dot clocks only or not at all. This means that if you can't find high-resolution modes for your monitor in these files, your monitor probably does not support those resolution modes.

If you are completely at a loss, and can't find working `ModeLine` values for your monitor, you can follow the instructions in the VideoModes.doc file included in the XFree86 distribution to generate `ModeLine` values from the specifications listed in your monitor's manual. While your mileage will certainly vary when attempting to generate `ModeLine` values by hand, this is a good place to look if you can't find the values you need. VideoModes.doc also describes the format of the `ModeLine` directive and other aspects of the XFree86 server in gory detail.

Lastly, if you do obtain `ModeLine` values that are almost, but not quite, right, it may be possible to simply modify the values slightly to obtain the desired result. For example, if while running XFree86 the image on the monitor shifts slightly or seems to "roll," you can follow the instructions in the VideoModes.doc file to try to fix these values. Also, be sure to check the knobs and controls on the monitor itself! In many cases it is necessary to change the horizontal or vertical size of the display after starting up XFree86 in order for the image to be centered and of the appropriate size. Having these controls on the front of the monitor can certainly make life easier. Another option is to use the program `xvidtune` (see the manual page for how to use it) that can help you to get all the numbers for the `modeline`, lets you try your changes, and even allows you to undo them if you did something wrong.

You shouldn't use monitor timing values or `ModeLine` values for monitors other than the model you own. If you attempt to drive the monitor at a frequency for which it was not designed, you can damage or even destroy it.

The next section of the XF86Config file is `Device`, which specifies parameters for your video card. Here is an example:

>     Section "Device"
>             Identifier "#9 GXE 64"

>             # Nothing yet; we fill in these values later.

>     EndSection

This section defines properties for a particular video card. `Identifier` is an arbitrary string describing the card; you will use this string to refer to the card later.

Initially, you don't need to include anything in the `Device` section, except for `Identifier`. This is because we will be using the X server itself to probe for the properties of the video card and entering them into the `Device` section later. The XFree86 server is capable of probing for the video-card chipset, clocks, RAMDAC (one of the chips on the video board), and amount of video RAM on the board.

Before we do this, however, we need to finish writing the XF86Config file. The next section is `Screen`, which specifies the monitor/video card combination to use for a particular server:

>      Section "Screen"
>          Driver     "Accel"
>          Device     "#9 GXE 64"
>          Monitor    "CTX 5468 NI"
>          Subsection "Display"
>              Depth      16
>              Modes      "1024x768" "800x600" "640x480"
>              ViewPort   0 0
>              Virtual    1024 768
>          EndSubsection
>      EndSection

The `Driver` line specifies the X server you will be using. The possible values for `Driver` are:

`Accel`

  For the XF86_S3, XF86_S3V, XF86_Mach64, XF86_Mach32, XF86_Mach8, XF86_8514, XF86_P9000, XF86_AGX, XF86_I128, XF86_TGA, and XF86_W32 servers

`SVGA`

  For the XF86_SVGA server

`VGA16`

  For the XF86_VGA16 server

`VGA2`

  For the XF86_Mono server

`Mono`

  For the non-VGA monochrome drivers in the XF86_Mono and XF86_VGA16 servers

Be sure that /usr/X11R6/bin/X is a symbolic link to your server; you might have to create this link yourself if you install XFree86 for the first time. Make a link with a command like the following:

>     ln -s /usr/X11R6/bin/XF86_SVGA /usr/X11R6/bin/X

Of course, you have to replace the first pathname with that of another server binary if you don't use the SVGA server.

The `Device` line specifies the `Identifier` from the `Device` section. Earlier, we created a `Device` section with the line:

>     Identifier "#9 GXE 64"

Therefore, we use `"#9 GXE 64"` on the `Device` line here.

Similarly, the `Monitor` line specifies the name of the `Monitor` section to be used with this server. Here, `"CTX 5468 NI"` is the `Identifier` used in the `Monitor` section described earlier.

`Subsection "Display"` defines several properties of the XFree86 server corresponding to your monitor/video-card combination. The XF86Config file describes all these options in detail; most of them are icing on the cake and are not necessary to get the system working.

The options you should know about are:

`DefaultColorDepth`

  Specifies the color depth to use in case the X server supports several color depths.

`Depth`

  Defines the number of color planes--the number of bits per pixel. Usually, `Depth` is set to 8. For the VGA16 server, you would use a depth of 4, and for the monochrome server a depth of 1. If you are using an accelerated video card or one of the better SVGA cards with enough memory to support more bits per pixel, you can set `Depth` to 16, 24, or 32. If you have problems with depths higher than 8, set it back to 8 and attempt to debug the problem later.

`Modes`

  Lists of video mode names that have been defined using the `ModeLine` directive in the `Monitor` section. In the previous section, we used `ModeLines` named `"1024x768"`, `"800x600"`, and `"640x480"`, so we use a `Modes` line of:

  >             Modes    "1024x768" "800x600" "640x480"

  The first mode listed on this line will be the default when XFree86 starts up. After XFree86 is running, you can switch between the modes listed here using Ctrl-Alt with the plus or minus on the numeric keypad.

  It might be best, when initially configuring XFree86, to use lower resolution video modes, such as 640x480, which tend to work on most systems. Once you have the basic configuration working, you can modify XF86Config to support higher resolutions.

`Virtual`

  Sets the virtual desktop size. XFree86 has the ability to use any additional memory on your video card to extend the size of your desktop. When you move the mouse pointer to the edge of the display, the desktop scrolls, bringing the additional space into view. Therefore, even if you are running at a lower video resolution, such as 800x600, you can set `Virtual` to the total resolution your video card can support. A 1 MB video card can support 1024x768 at a depth of 8 bits per pixel, while a 2 MB card can support 1280x1024 at depth 8, or 1024x768 at depth 16. Of course, the entire area will not be visible at once, but it can still be used.

  The `Virtual` option is a nice way to utilize the memory of your video card, but it is rather limited. If you want to use a true virtual desktop, we suggest using a window manager like `kwm` or `fvwm2` instead. Both allow you to have rather large virtual desktops (implemented by such software techniques as hiding windows instead of actually storing the entire desktop in video memory at once). See the next chapter for more details about this; most Linux systems use `kwm`, which is a part of the K Development Environment, by default.

`ViewPort`

  If you are using the `Virtual` option described earlier, `ViewPort` sets the coordinates of the upper-left corner of the virtual desktop when XFree86 starts up. `ViewPort 0 0` is often used, putting the screen at the top left corner of the desktop; if this is unspecified, the desktop is centered on the virtual desktop display (which may be undesirable to you).

Many other options for this section exist; see the XF86Config manual page for a complete description. In practice, these other options are not necessary to get XFree86 working initially.

Copyright © 2001 O'Reilly & Associates. All rights reserved.